6. Using FileFlex in XFCN Environments

Besides working in Director, the professional version of FileFlex will work with any application that allows you to run XFCNs (on the Macintosh) and Director 4 (on both Macintosh and Windows). There are thirty or more of these applications, including Director 4, Authorware, Frontier, SuperCard and many others.

One of the design goals for FileFlex is that the data set you use (the FileFlex database files) and the instructions you use to control access to the data (the DBxxx instructions) are identical, regardless of which development environment you're in. Most users will generally work in one environment, but there are times that it's necessary to use one development tool for one purpose and another for another purpose. In these instances, FileFlex can come in very handy to make sure you've got common data and don't need to learn another API.

Because each of these applications are very different, their development environments and development requirements vary greatly. As a result, we can't provide you with detailed instructions for each tool. What we can do is provide general techniques and background for using FileFlex in pretty-much any XCMD-compatible application.

The FileFlex "Wrapper" Mechanism


In most environments, when you make a call to FileFlex, you're really executing a script "wrapper" that then calls the actual XFCN code resource. Here's a sample of one such wrapper: 
  Function DBSeek seekExpr
    DBCheckActive 
    return FileFlex (13, seekExpr)
  End DBSeek
In the above wrapper, the actual XFCN call is "FileFlex (13, seekExpr)"; the other lines define the DBSeek function and execute the HyperTalk handler DBCheckActive.

So, if there's only a few lines around the XFCN call, why use wrappers at all?

There are three reasons: Wrappers are wonderful tools. But....

...wrappers can't be used if you're developing something in one of the thirty or so products that support XFCNs but we have not supplied wrappers for (e.g., Authorware, UserLand Frontier, Software Ventures Microphone, etc.)

If you use these functions, you'll have to call the XFCN directly. The direct XFCN calls are described in detail in the Direct FileFlex API Interface.

General Compatibility Issues

FileFlex will work well with almost all XCMD-compatible environments. The XCMD standard originated in HyperCard and has since been adopted by a number of other tool vendors. There are a few things to keep in mind, however.

FileFlex requires the GetGlobal and SetGlobal HyperCard XCMD callback to be implemented. This is because FileFlex demands access to two specific globals, gdbglobalptr1030 and gdberrorflag. This is normally not a problem with most tools that provide XCMD support. But if you encounter inconsistent behavior in your development tool, check with the vendor and make sure GetGlobal and SetGlobal callbacks are supported.

If you want to get or send data to FileFlex-and you're not using something that maps field information directly (like HyperCard or SuperCard)-you'll need to avoid the "B" and "C" parameters. Bring the card information into variables using DBGetFieldByName or DBGetFieldByNum. You can also bring the entire record into a variable with DBGetCurrRecVal("L")-or any non-"B" or non-"C" parameter. Then parse the variable data down into usable chunks.

If your environment supports the SetGlobal and GetGlobal callbacks (most do), you may want to send and retrieve data from global variables using the "G" option. Make sure you understand how your environment deals with globals so you avoid surprises.

Using FileFlex with Director 4

FileFlex is no longer supported for use with Director 4. If you really need it, consider using FileFlex v1.7, which is available for download from the Component web site. We strongly recommend you upgrade to Director 5. Please note that while Director 5 supports the XFCN interface, we've taken special pains to develop high-performance Xtra interfaces to Director and will not be supporting using the XFCN version of FileFlex with Director 5.

Using FileFlex with HyperCard


In HyperCard, FileFlex provides a mechanism through DBWriteRec and DBGetCurrRecVal that provides a one-for-one mapping between like named fields in FileFlex files and HyperCard stacks. To access this feature, you'd use the "B"(for background) or "C" (for card) parameters to tell FileFlex where to send the data.

The professional edition of FileFlex ships with a test bench for use in HyperCard, as well as a "goodies" stack with additional tools.

Using FileFlex with Authorware Professional

In Authorware, it seems that globals retain their value (i.e., they're static). This means the value of gDBActive1030 will not reset to empty when you exit your Authorware production. You must use extra care to set gDBActive1030 to empty when you leave or start your production.

We are working towards a well-supported version of FileFlex for both Authorware Windows and Authorware Macintosh. Be sure to subscribe to the FileFlex listserv and visit the website for announcement details.

Using FileFlex with UserLand Frontier/Aretha

Frontier, from version 2.0 on, supports XCMDs and XFCNs. Frontier treats everything as a function returning a value. FileFlex fits very well into this model. In fact, it's pretty neat to see the Frontier object database interact with the FileFlex databases.

Frontier ships with a special droplet that installs XCMDs and XFCNs directly into the root file. Make sure when you install the FileFlex XCFN that the code resources also follow along. Frontier data elements in the object database are static. As in Authorware, you'll need to be sure to set gDBActive1030 to empty explicitly when leaving Frontier.

Using FileFlex with SuperCard 2.x

FileFlex works very nicely with SuperCard 1.6 and above (we recommend you use SuperCard 2.x and up). Because SuperCard is so much like HyperCard, you can even use the wrapper mechanism and the "B" and "C"parameters to DBGetCurrRecVal and DBWriteRec.

Open the FileFlex stack and copy the stack script into your project script. This will give you access to the wrappers that are so valuable for development and debugging.

SuperCard uses a unique mechanism of storing most resource information in the data fork. Although the FileFlex XFCN can be converted to the data fork format, it expects to find its supporting code resources in the resource fork. Make sure that you have access to the code resources in the resource fork before attempting to run FileFlex from within your SuperCard project.

Since FileFlex consists of an XFCN resource and five CODE resources, things can get confusing. When the XFCN loads, it expects to look into the resource fork for the CODE resources. To make FileFlex function properly, call openResources with the appropriate parameters in your openProject handler and closeResources in the closeProject handler. (Thanks to Andrew Meit for researching this for us!)

Also remember that your resources and data fork quasi-resources will live in different places in standalone projects and editable projects. When you create your own standalone, make sure you've grabbed the appropriate code resources from the SuperCard sharedfile.

Installing XFCN-Based FileFlex

There is no formal installer program for FileFlex. Just copy the files off the distribution disk to your desired location on your hard drive volume of choice.

Referencing FileFlex as an External Function

The very best way to use FileFlex is via your development tool's equivalent to HyperCard's "start using" command. This allows you to call on FileFlex' resources without needing to embed either the wrapper scripts nor the XFCNs within your application-making it MUCH easier to update. Many other development tools have a similar external library reference function (in Director, it's called "openXLib", in SuperCard, it's "open resources").

Installing the XFCN Resources

If you must install FileFlex into your project, you'll need to be sure to install the FileFlex XFCN into your project. This is done using ResEdit or some other resource editor. If you don't have (or don't know how to use) ResEdit, you should use the "start using" method. Just open up the FileFlex file in the resource editor, look for the single FileFlex XFCN, and copy it into your project.

Note: Since version 1.7, FileFlex does not require 'CODE' resources!

Installing the Wrapper Scripts

We've provided wrapper scripts to help you call the FileFlex externals. For HyperCard and SuperCard users, the wrapper scripts are stored in the stack script of the FileFlex stack.

Upgrading FileFlex in an Existing Project

We're hoping that most people using FileFlex are using the "start using"method of accessing the functions. If so, upgrading is a simple matter of deleting the old FileFlex stack and calling on the new one.

Here's what you need to do to clear out the old FileFlex and use the new one (or if you wish to install FileFlex in files of your choosing): That should do it. Have fun! 

  [Previous Chapter]    [Table of Contents]    [Next Chapter]
Copyright (c) 1996 David Gewirtz under license to Component Software Corp. All rights reserved worldwide.